/******************************************************************************
 * @file rd0ff_bsp_exti_handler.h
 * @brief EXTI处理器头文件
 *
 * 详细描述：
 * - 功能1：提供EXTI处理器的高层封装接口
 * - 功能2：实现EXTI事件采集、处理和事件分发功能
 * - 功能3：兼容操作系统环境，通过队列线程处理中断事件
 * - 功能4：提供中断统计和状态监控功能
 *
 * @author 陈泳行 | R&D Dept. | Jin Dou Aerospace 金斗航天
 * @date 2025-7-15
 * @version 1.0.0
 *
 * @version_history
 * - 1.0.0 (2025-7-15): 初始版本，实现基本功能
 *
 * @note 本模块依赖EXTI驱动层和操作系统抽象
 * @warning 处理器初始化前必须确保EXTI驱动已完成初始化
 ******************************************************************************/
#ifndef __RD0FF_BSP_EXTI_HANDLER_H
#define __RD0FF_BSP_EXTI_HANDLER_H
#include <stdio.h>
#include <stdint.h>

#include "rd0ff_bsp_exti_driver.h"

/**
 * @brief EXTI处理器操作返回状态码枚举
 *
 * 此枚举扩展了驱动层状态码，增加了处理器层的错误类型，用于更细致的错误处理。
 */
typedef enum
{
    EXTI_HANDLER_RET_OK = 0,                  /* 操作成功                              */
    EXTI_HANDLER_RET_ERROR,                   /* 通用错误：未指定的错误				  */
    EXTI_HANDLER_RET_INVALID_PARAM,           /* 参数错误：传入的参数值无效             */
    EXTI_HANDLER_RET_INVALID_STATE,           /* 状态错误：设备处于非法状态             */
    EXTI_HANDLER_RET_INVALID_MODE,            /* 模式错误：不支持的操作模式             */
    EXTI_HANDLER_RET_INVALID_DATA,            /* 数据错误：数据格式或内容无效           */
    EXTI_HANDLER_RET_INVALID_LENGTH,          /* 长度错误：数据长度超出有效范围         */
    EXTI_HANDLER_RET_INVALID_ADDRESS,         /* 地址错误：无效的内存或设备地址         */
    EXTI_HANDLER_RET_INVALID_VALUE,           /* 值错误：参数值超出有效范围             */
    EXTI_HANDLER_RET_INVALID_FUNCTION,        /* 函数错误：无效的函数指针或未实现       */
    EXTI_HANDLER_RET_INVALID_INTERRUPT,       /* 中断错误：中断配置或处理失败           */
    EXTI_HANDLER_RET_INVALID_TIMER,           /* 定时器错误：定时器配置或操作失败       */
    EXTI_HANDLER_RET_INVALID_QUEUE,           /* 队列错误：队列操作或配置失败           */
    EXTI_HANDLER_RET_QUEUE_FULL,              /* 队列满：事件队列已满，无法添加新事件   */
    EXTI_HANDLER_RET_QUEUE_EMPTY,             /* 队列空：事件队列为空，无事件可处理     */
    EXTI_HANDLER_RET_CALLBACK_ERROR,          /* 回调错误：回调函数执行失败             */
} exti_handler_ret_t;

/**
 * @brief EXTI事件结构体
 *
 * 包含EXTI处理器内部传递和外部模块传递的事件信息。
 */
typedef struct
{
    bsp_exti_line_t exti_line;               /* 触发事件的EXTI线号                    */
    bsp_exti_event_type_t event_type;        /* 事件类型（上升沿/下降沿/超时/错误）    */
    uint32_t timestamp;                      /* 事件时间戳                            */
    uint32_t gpio_state;                     /* 触发时的GPIO状态                      */
} exti_event_t;

/**
 * @brief EXTI处理器操作系统接口结构体
 *
 * 封装操作系统相关功能，实现跨操作系统的兼容性，支持不同OS环境。
 */
typedef struct 
{
    os_delay_t          *os_delay_ms;         /* OS延迟函数结构体指针                  */
    exti_handler_ret_t (*exti_queue_create )(void** queue_handle, 
                                             uint32_t queue_size, 
                                             uint32_t item_size  );/* 创建事件队列函数 */
    exti_handler_ret_t (*exti_queue_delete )(void* queue_handle  );/* 删除事件队列函数 */
    exti_handler_ret_t (*exti_queue_send   )(void* queue_handle, 
                                             void* item, 
                                             uint32_t timeout_ms );/* 发送队列函数 */
    exti_handler_ret_t (*exti_queue_receive)(void* queue_handle, 
                                             void* item, 
                                             uint32_t timeout_ms );/* 接收队列函数 */
} exti_handler_os_t;

/**
 * @brief EXTI处理器初始化输入结构体
 *
 * 用于初始化EXTI处理器时传递必要的接口和资源。
 */
typedef struct
{
    time_base_t *  time_base;                 /* 时间基准结构体指针                    */
    bsp_exti_t   *        exti;               /* EXTI驱动接口结构体指针                 */
    exti_handler_os_t *   os;                 /* OS接口结构体指针                      */
} exti_input_t;

/**
 * @brief EXTI私有数据前向声明
 *
 * 隐藏具体实现细节，提高封装性。具体定义在.c文件中。
 */
typedef struct exti_private_data exti_private_data_t;

/**
 * @brief EXTI处理器实例结构体
 *
 * 包含EXTI处理器的所有资源、接口和状态，是EXTI处理器的核心数据结构。
 */
typedef struct 
{
    /* 外部传入的接口 */
    time_base_t         *   time_base;        /* 时间基准结构体指针，用于时间戳获取     */
    bsp_exti_t          *         exti;       /* EXTI驱动接口结构体指针                 */

    /* 操作OS的接口 */
    exti_handler_os_t   *          os;        /* OS接口结构体指针，提供队列和延迟功能   */

    /* 驱动实例 */
    bsp_exti_driver_t   * exti_driver;        /* EXTI驱动实例指针                      */

    /* 私有数据*/
    exti_private_data_t * private_data;       /* 私有数据指针，存储运行时状态           */

    /* 事件队列 */
    void* queue_handle;                       /* 事件队列句柄，用于异步事件处理         */
} exti_handler_t;

/**
 * @brief EXTI处理器线程函数
 *
 * EXTI事件处理主循环线程，负责事件采集、处理和事件分发
 *
 * @param arg 线程参数，通常为exti_handler_t实例指针
 */
void exti_handler_thread(void *arg);

/**
 * @brief EXTI处理器实例初始化函数
 *
 * 初始化EXTI处理器实例，绑定底层驱动接口和OS接口，创建必要资源。
 *
 * @param exti_handler EXTI处理器实例指针
 * @param exti_input 初始化输入参数结构体指针
 *
 * @return exti_handler_ret_t 操作结果状态码
 * @retval EXTI_HANDLER_RET_OK 初始化成功
 * @retval EXTI_HANDLER_RET_INVALID_PARAM 参数无效
 * @retval EXTI_HANDLER_RET_ERROR 初始化失败
 */
exti_handler_ret_t exti_handler_inst(exti_handler_t *exti_handler, 
                                     exti_input_t   *exti_input   );

/**
 * @brief 注册EXTI线回调函数
 *
 * 为指定的EXTI线注册中断回调函数
 *
 * @param exti_handler EXTI处理器实例指针
 * @param exti_line EXTI线号
 * @param callback 回调函数指针
 *
 * @return exti_handler_ret_t 操作结果状态码
 */
exti_handler_ret_t exti_register_callback(exti_handler_t *exti_handler,
                                          bsp_exti_line_t exti_line,
                                          void (*callback)(uint32_t));

/**
 * @brief 注销EXTI线回调函数
 *
 * 注销指定EXTI线的回调函数
 *
 * @param exti_handler EXTI处理器实例指针
 * @param exti_line EXTI线号
 *
 * @return exti_handler_ret_t 操作结果状态码
 */
exti_handler_ret_t exti_unregister_callback(exti_handler_t *exti_handler,
                                            bsp_exti_line_t exti_line);

/**
 * @brief 获取EXTI统计信息
 *
 * 获取指定EXTI线的中断统计信息
 *
 * @param exti_handler EXTI处理器实例指针
 * @param exti_line EXTI线号
 * @param interrupt_count 中断计数器指针
 * @param last_timestamp 最后中断时间戳指针
 *
 * @return exti_handler_ret_t 操作结果状态码
 */
exti_handler_ret_t exti_get_statistics(exti_handler_t *exti_handler,
                                       bsp_exti_line_t exti_line,
                                       uint32_t *interrupt_count,
                                       uint32_t *last_timestamp);

#endif /* END __RD0FF_BSP_EXTI_HANDLER_H */